<?php
/**
 * @file Db.php
 *
 * Database representation.
 *
 * With this class you can interact with the databases. It uses by default the
 * connection in configuration.php for establishing a connection.
 *
 * New BSD License
 * \n
 * Copyright (c) 2010 Rpd-Team
 */

/**
 * Connection to a Database
 * @since  0.0.9
 *
 * This class represent a connection to a database and can send queries to it.
 *
 *
 * @section Changelog
 *
 * <table>
 * 	<tr>
 * 		<th>Version</th>
 * 		<th>Description</th>
 *  </tr>
 *  <tr><td>0.1.0</td><td>insert_id() returns the last inserted ID</td></tr>
 * </table>
 *
 *
 * @section Examples
 *
 *
 * @see Model
 *
 */
class Db {
	protected $_sql;

	function database($name)
	{
		$this->_sql->database($name);
	}

	/**
	 * Last inserted ID
	 *
	 * After running an insert this function gives you the last generated ID.
	 *
	 * @since 0.1.0
	 *
	 * @return integer Last generated ID
	 *
	 * @section Changelog
	 *
	 * <table>
	 * 	<tr>
	 * 		<th>Version</th>
	 * 		<th>Description</th>
	 *  </tr>
	 *  <tr><td></td><td></td></tr>
	 * </table>
	 *
	 * @section Examples
	 *
	 * @subsection Db_query_insert_id Get last inserted ID
	 *
	 * <pre>/app/Controller/index.php</pre>
	 * @code
	 * <?php
	 *
	 * // connect to database
	 * $db = new Db();
	 *
	 * // run some insert
	 * $db->query("INSERT INTO some_table (some_field) VALUES (123)");
	 *
	 * // show ID that has been generated in the table
	 * echo $db->insert_id();
	 *
	 * ?>
	 * @endcode
	 *
	 * <pre>Output "/"</pre> (will be the according ID)
	 *
	 * @see Db::query
	 */
	function insert_id()
	{
		return $this->_sql->insert_id();
	}

	/**
	 * Executes a query
	 * @since 0.0.1
	 *
	 * @param string $statement A SQL-Query
	 * @param string $escape1 Text to escape
	 * @param string $escape2 ...
	 *
	 * @return An iterateable Db_Statement
	 *
	 * @section Changelog
	 *
	 * <table>
	 * 	<tr>
	 * 		<th>Version</th>
	 * 		<th>Description</th>
	 *  </tr>
	 *  <tr><td>0.0.9</td><td>Able to escape incoming values</td></tr>
	 * </table>
	 *
	 * @section Examples
	 *
	 * @subsection Db_query-easy_query Run query
	 *
	 * <pre>/app/Controller/index.php</pre>
	 * @code
	 * <?php
	 *
	 * // make new instance
	 * $db = new Db();
	 *
	 * // run some query
	 * $statement = $db->query("SELECT * FROM some_table");
	 *
	 * ?>
	 * @endcode
	 *
	 *
	 * @subsection Db_query-Escape Escape characters
	 *
	 * Consider the topic "SQL Injections". Some users try to harm your site
	 * with SQL statements within your forms. This will cause the system to
	 * show them every information they want as long as you don't escape them.
	 *
	 * <pre>/app/Controller/index.php</pre>
	 * @code
	 * <?php
	 *
	 * $sensitive = "' || '' = '";
	 *
	 * // make new instance
	 * $db = new Db();
	 *
	 * // run query with escaped chars
	 * $statement = $db->query("SELECT * FROM users WHERE name = '%s'",
	 *                          $sensitive);
	 *
	 * ?>
	 * @endcode
	 *
	 * @see Db::__construct()
	 * @see Db_Statement
	 */
	function query($statement)
	{
		if (func_num_args() > 1)
		{
			$a = func_get_args();
			array_shift($a);
			return $this->_sql->query($statement, $a);
		}

		return $this->_sql->query($statement);
	}

	/**
	 * Constructor for new Db instance
	 * @since 0.0.1
	 * @param string $settings Connection settings
	 * @return Nothing except an instance of Db when used with "new Db();"
	 *
	 * @section Changelog
	 *
	 *  <table>
	 * 	<tr>
	 * 		<th>Version</th>
	 * 		<th>Description</th>
	 *  </tr>
	 *  <tr><td></td><td></td></tr>
	 * </table>
	 *
	 * @section Examples
	 *
	 * @subsection Db_Config Connect using configuration
	 *
	 * <pre>/configuration.php</pre>
	 * @verbatim [db/std]
 server     = 127.0.0.1      ; address to your server
 user       = some_username
 password   = some_password
 database   = some_database
 driver     = mysql          ; server runs on ...
 persistent = 0              ; keep persistent connections? (0=no, 1=yes)
 encoding   = UTF-8 @endverbatim
	 *
	 * <pre>/app/Controller/index.php</pre>
	 * @code
	 * <?php
	 *
	 * $db = new Db();		// uses "db/std" by default
	 *
	 * // use another configuration
	 * $db = new Db(Registry::get("db/std"));
	 *
	 * ?>
	 * @endcode
	 *
	 * @subsection Db_Array Manually connect
	 * <pre>/app/Controller/index.php</pre>
	 * @code
	 * <?php
	 *
	 * $settings = array(
	 *   "server"     => "127.0.0.1",
	 *   "user"       => "some_username",
	 *   "password"   => "some_password",
	 *   "database"   => "some_database",
	 *   "driver"     => "mysql",
	 *   "persistent" => 0,
	 *   "encoding"   => "UTF-8"
	 * );
	 *
	 * $db = new Db($settings);
	 *
	 * ?>
	 * @endcode
	 */
	function __construct($settings = NULL)
	{
		if ($settings === NULL)
		{
			$settings = Registry::get("db/std");
		}


		$class = "Db_Adapter_" . strtolower($settings["driver"]);
		if (class_exists($class))
		{
			$this->_sql = new $class($settings);
		}
		else
		{
			throw new Error("Unknown driver " . $settings["driver"]);
		}

		$this->_sql->database($settings["database"]);
		$this->_sql->encoding($settings["encoding"]);
	}
}

?>